glplatform
==========

`glplatform` provides a framework for developing OpenGL applications without taking control over the application's main loop. It handles window creation, event processing, OpenGL context management, and OpenGL binding management. `glplatform` is designed to make it easy to create an OpenGL application but does not serve as general purpose platform abstraction library. At present GNU/Linux and Windows are supported. Support for other platforms may be added later as variants of the present interface.

Creating a window
-----------------

A window can be created in by calling `glplatform_create_window()` specifying its title, initial dimentions, framebuffer format, and a structure containing event callbacks. If no framebuffer format is specified then a framebuffer 24-bit color buffer and a 24-bit depth buffer will be requested. The event callbacks will be called inside `glplatform_process_events()` (see below).

Example: Create a "Hello world" window

	#include <glplatform/glplatform.h>

	void on_key_down(struct glplatform_win *win, int k)
	{
		printf("Key pressed: %c\n", k);
	}

	int main()
	{
		struct glplatform_win_callbacks cb = {
			.on_key_down = on_key_down
		};

		struct glplatform_win *win = glplatform_create_window("Hello window", &cb, NULL, 512, 512);
		//...
	}

Event processing
----------------

`glplatform` invokes callbacks for previously queued events when `glplatform_process_events()` is called. Events are queued by `glplatform_get_events()`.

Example: A simple main loop

	int main()
	{
		//...
		while (glplatform_process_events()) {
			if (glplatform_get_events(true) < 0)
				break;
		}
	}

If false is passed into `glplatform_get_events()` then `glplatform` will not block and returns the number of events queued, allowing the user to poll for events. On Linux `glplatform` uses `epoll()` to wait for events and it exposes the epoll file descriptor it uses to the application as `glplatform_epoll_fd`. This may allow for `glplatform` event processing to be performed in combination with other event processing systems without polling.

Creating an OpenGL context
--------------------------

When creating a context you must specify which OpenGL version your application requires and the window that the context will be rendering to. The version on the returned context may be higher but will be backwards compatible with the requested version. The returned context will always be a core profile context. Before OpenGL calls can be made the context must be made current with `glplatform_make_current()`. This causes OpenGL commands in the current thread to operate in the context.

Example: Creating a OpenGL 3.3 core profile compatible context

	struct glplatform_win *win = glplatform_create_window("Hello window", &cb, NULL, 512, 512);

	//...

	glplatform_gl_context_t ctx = glplatform_create_context(win, 3, 3);
	if (!ctx)
		exit(-1)

	glplatform_make_current(win, ctx);

Function pointer binding
------------------------

Once a context has been made current OpenGL calls cannot be issued until the OpenGL API's function pointers are bound. `glplatform` contains bindings generated by `glbindify` for this purpose.

Example: Initializing OpenGL bindings

	#include <glplatform/glplatform.h>
	#include <glplatform/glplatform-glcore.h>

	int main()
	{
		struct glplatform_win *win;
		glplatform_gl_context_t ctx;

		//...

		glplatform_make_current(win, ctx);

		if (!glplatform_glcore_init(3, 3)) {
			exit(-1);
		}
	}


See the `glbindify` documentation for details. Note that `glplatform` uses the namespace feature of `glbindify` so where the documentation refers to `glb` or `GLB` you should substitute `glplatform` or `GLPLATFORM`
respectively.

Text rendering
--------------

glplatform contains a text renderer that

- Is data Driven for minimal driver overhead

- Works on OpenGL 3.x and higher

- Uses libfreetype for text rasterization

glplatform's text renderer can render transformed text with minimal distortion as well as render untransformed text with high quality anti-aliasing. Its design focuses on simplicity, performance, and control.

To render text an application first requests an array of glyph instance structures. The application must then fill the entries with glyph positions and glyph identifiers. Finally the application submits the draw specifying the color and transform to perform the rendering with. Glyph metrics and kerning information that can be queried from the API to help the application layout the glyphs. The render call supports rotation and scaling of the text in three dimentions.

Building
--------

`glplatform` can be built with it's autotools build system with the following commands:

	./autogen.sh
	./configure <options>
	make
	make install

You can build `glplatform` for windows systems by placing a MinGW64 toolchain in the path and passing a host option such as `--host=x86_64-w64-mingw32` to configure.

As a convienence `glplatform` comes with bindings pre-generated by `glbindify`. To rebuild them install `glbindify` and run the following commands
in the `src/glbindings` folder:

	glbindify -a gl -n glplatform
	glbindify -a wgl -n glplatform
	glbindify -a glx -n glplatform
